home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / utilities / pu133.dms / pu133.adf / PowerPacker / PowerPacker.doc / PowerPacker.doc
Text File  |  1991-07-28  |  34KB  |  766 lines
  1.  
  2.                              Power Packer 2.3B
  3.                              ~~~~~~~~~~~~~~~~~    
  4.                            Program & Data Cruncher.
  5.  
  6. Here we have another version of Nico Francois' excellent PowerPacker
  7. Program and Data file cruncher, although previous versions have been 
  8. on earlier updates we believe this has sufficient additions to merit 
  9. inclusion yet again. 
  10.  
  11. The main reason for it`s inclusion is because of the ENCRYPT option,
  12. many people have phoned in wanting some sort of password util or 
  13. encoder so they can keep private files private and away from unwanted 
  14. eyes, by using the Encode option you can crunch your Ascii text files 
  15. and encrypt them, making decrunching/reading only possible after 
  16. entering your password!! To see how the encryption works try double 
  17. clicking the Encryption.Example icon - once PPmore has loaded you will 
  18. see the password entry box - the correct password is TEST  , you can 
  19. try an incorrect one to see what happens when you get the password wrong!
  20. For more details on how this section works please see section 1.3.3 of 
  21. Nico's documentation. 
  22.  
  23. Unfortunately the docs are for version 2.3a not 2.3b (I seem to have 
  24. mislaid/erased these - sorry!!) but they cover vitually all the 
  25. features of 2.3b aswell, so this shouldn't cause too many problems!
  26.  
  27.                        
  28. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  29.  
  30. Preface
  31. =======
  32.  
  33.      Congratulations, you have just obtained a copy of PowerPacker 2.3a,
  34. PowerPeak's command and data cruncher for the Amiga.  If you have suggestions
  35. or remarks about this program, or if you find any bugs, please let me know.
  36.      This version of PowerPacker is shareware, this means that if you use it
  37. a lot I would appreciate it if you'd send me a contribution of $10 US or the
  38. same amount in any other currency.  This money will enable me to produce more
  39. programs on the Amiga.  If you send $15 US ($20 US overseas) I will send you
  40. the latest version of PowerPacker.  Please send money by international money
  41. order, EuroCheck (in Belgian Francs (BF) !!!!!) or cash, it's difficult for
  42. me to cash in other checks.  If you send for an update please state your
  43. current version, if there is no higher version at the time I get your letter
  44. I won't reply until I finish the next version, so don't be alarmed if it
  45. takes a while !
  46.      If  you want to use PowerPacker for commercial purposes you need written
  47. permission.
  48.  
  49.      Write to the following address:
  50.  
  51.                                 Nico Francois
  52.                                 Corbielaan 13
  53.                              3060 Bertem BELGIUM
  54.  
  55.  
  56.  
  57. 1. The Packer
  58. -------------
  59.  
  60. 1.1 An introduction
  61.  
  62.      PowerPacker is a userfriendly command and data cruncher, this means a
  63. menu driven utility that can crunch almost any file on your disks.  It can be
  64. started from the CLI or the WorkBench, just type it's name in the CLI window
  65. or doubleclick it's icon.  PowerPacker will detach itself from the CLI so you
  66. can close the CLI window.  When you use it for the first time it's best to
  67. maintain a certain order in your actions (as we will see in chapter 6 of this
  68. document):
  69.  
  70.   (a) Check the packer options at the beginning of a session (Prefs menu)
  71.   (b) Load the file from disk (Project menu)
  72.   (c) Wait for the file to (de)crunch.
  73.   (d) Save the file back to disk (Project menu)
  74.  
  75.      Apart from crunching, you can also recrunch files that were crunched by
  76. most other crunchers.
  77.      The HunkLab enables you to e.g. force code or data in chip ram.
  78.      The script allows you to e.g. crunch a dozen of files overnight.
  79.  
  80.      Before I demonstrate how to use PowerPacker, let's look at the file
  81. requester and a brief overview of the menus and capabilities.
  82.  
  83.  
  84. 1.2 The file requester
  85.  
  86.     Whenever you are required to enter a filename, the packer sets up a file
  87. requester.  This requester automatically contains all devices connected to
  88. your Amiga and lists all the files (and their length) of a selected
  89. directory.  You don't have to wait for the directory read to end.  You can
  90. select a file or directory the moment you see it, or you can enter it in the
  91. appropriate string gadget.
  92.     However, if you wait for the directory read to end and quit the file
  93. requester, the next time you use it all the files will still be there, so you
  94. don't have to wait for the directory to be read again (This is very useful
  95. when you are recording a script, as you'll see later).  This feature has one
  96. disadvantage :  if files are changed or added to the selected directory they
  97. won't be shown in the list, or they will be shown with the wrong filelength,
  98. the next time the requester appears.  Therefore, if you think anything has
  99. been changed to the selected directory, use the 'GET DIR' gadget to re-read
  100. the directory.  (E.g.  when you save a crunched file on top of the old one,
  101. the old file length will be shown in the requester.)
  102.      When the 'Sort Files' switch in the prefs menu is checked the files will
  103. be alphabetically sorted in the requester.  This switch is present because
  104. some people don't like the files being sorted and jumping up and down the
  105. requester, they think it's annoying to try and catch the file you want. (and
  106. they are right of course :-)
  107.  
  108.  
  109. 1.3 The basic menus
  110.  
  111. 1.3.1 Project
  112.  
  113.     The project menu contains the file manipulation options.  Most of them
  114. speak for themselves:
  115.  
  116.   Load      ->  Load a file from disk and start the (de)crunching.
  117.   Save      ->  Save the (de)crunched or processed file in memory to disk.
  118.   Delete    ->  Delete a file from disk.
  119.   WorkBench ->  Open or close WorkBench if possible. (Adds 42K !)
  120.   Sleep     ->  Put PowerPacker to sleep on the WorkBench Screen, this
  121.                 frees 40-50K.
  122.                 WARNING: All buffers will be deallocated, so you are advised
  123.                          to save things first.
  124.   About...  ->  Show general information and my address.
  125.   Quit      ->  Quit the program.
  126.  
  127. 1.3.2 Prefs
  128.  
  129.      The prefs menu contains all the (de)cruncher settings.  You can select
  130. to (de)crunch command files or a data files.  If you want the crunched
  131. version of your file to be executable, select 'Command file'.  Now
  132. PowerPacker knows it has to add a decrunch header (572 bytes).  If the file
  133. you want to crunch only contains data (e.g. source codes of your programs),
  134. select the 'Data file' option.  This can be handy if you're going to use the
  135. PowerPacker CLI commands.  I'll discuss these commands in chapter 7 of this
  136. document.  Finally you have to choose whether you want to crunch or decrunch
  137. the load file.
  138.  
  139. NOTE: - PowerPacker will automatically decrunch a previously crunched
  140.         file.  You don't have to select crunch or decrunch mode anymore as
  141.         in PowerPacker 2.0a.
  142.  
  143.      The 'Decrunch Color' submenu contains the following options :
  144.  
  145.   Color 0   ->  The background color will change while decrunching
  146.   Color 1   ->  The text color changes
  147.   Pointer   ->  Only the mousepointer's color changes
  148.   Scroll    ->  Handy for decrunching a demo (just try it out !)
  149.   None      ->  If your eyes are wearing out.
  150.  
  151.      These options indicate what color will flash when a file is decrunched.
  152. You can change this option before saving a crunched file, so you can save a
  153. version of your crunched program that flashes in color 1, and one that
  154. flashes in the mouse pointer.  The default value is 'Pointer'.
  155.  
  156.      In the efficiency submenu you will find the following possibilities :
  157.  
  158.   Fast      ->  Use for small files, or for quick crunch.
  159.   Mediocre  ->  Better but slower.
  160.   Good      ->  Default, gains 40-50% in most cases.
  161.   Very Good ->  Also very slow !
  162.   Best      ->  Advised for script use only, ultra slow !!!
  163.  
  164. NOTE: - 'Fast' is approx. 4 times faster than 'Good', 'Very Good' is
  165.         2 times slower and 'Best' 4 times.
  166.       - 'Best' isn't always the best.  Small files crunch best with
  167.         'Very Good' or even 'Good'.
  168.  
  169.      The remaining preference switches:
  170.  
  171.   Data suffix  -> Attach '.pp' suffix to data files after crunching or remove
  172.                   '.pp' after decrunching.  It is advised that you leave this
  173.                   switch on so you can easily spot crunched data files.
  174.   Encrypt Data -> See section 1.3.3 of this manual.
  175.   Color Crunch -> Flash the selected decrunch color when crunching, giving
  176.                   you an idea what the decrunching will look like (provided
  177.                   that you don't change any options just before saving to
  178.                   disk).
  179.   LED Crunch   -> Your power-LED flashes while crunching, just like the
  180.                   screencolors. Now, you can even turn off your monitor and
  181.                   still see when the cruncher has finished.
  182.   Multitask    -> Switch multitasking off to (sligtly) increase the crunching
  183.                   speed.
  184.   Paging       -> Pause and wait for mouse button when supervisor window
  185.                   fills up.
  186.   Overwrite    -> Don't prompt if it's ok to overwrite a file when saving.
  187.   Sort files   -> Sort files in file requester.
  188.  
  189.      Use 'Save prefs' to save the preferences to your boot disk.  The
  190. preferences will be saved in the file 's:PowerPacker.prefs', this file will
  191. be enormous, euh, 6 bytes big.  When PowerPacker 2.3a is first started it
  192. will attempt to load this file and adjust the preferences.
  193.  
  194. NOTE: - While crunching, you can press both mousebuttons at the same
  195.         time to abort.
  196.       - Do *NOT* change disks when you are crunching with the multitasking
  197.         switched off !!!  The Amiga will crash !!!
  198.  
  199. 1.3.3 Crypt
  200.  
  201.      When the 'Encrypt Data' switch is on PowerPacker will not only crunch
  202. data files, it will also encrypt them so nobody else but you can decrunch
  203. them.  Just before crunching a data file PowerPacker will ask you for a
  204. password.  You will be presented with a string gadget with a special feature,
  205. it won't show you what you are typing !  After entering your password you
  206. will be asked to enter it again, this is done to verify that you haven't made
  207. a typing error (unless you make the same error twice :-).
  208.      You can also use the 'Last' gadget to re-enter your last password again,
  209. or the 'Abort' gadget to abort the encryption and just crunch the file.
  210.      When you try to load a crunched encrypted data file PowerPacker will
  211. once again prompt you for your password.  If you enter the correct one the
  212. data file will be decrypted and decrunched.  If you don't know the password,
  213. bad luck, there is no way you can decrunch this file !!
  214.  
  215. NOTE: - Encryption can currently not be used in a script.
  216.       - Your password can be up to 16 characters long, any character is
  217.         accepted, lowercase and uppercase are DIFFERENT !!!!
  218.       - Take care when using the 'Last' gadget, be sure to know what your
  219.         last password was.
  220.       - Don't forget your password !!  It is *IMPOSSIBLE* to decrypt a file
  221.         without the password !!!!!
  222.  
  223.  
  224. 2. Recrunch
  225. -----------
  226.  
  227. 2.1 How ?
  228.  
  229.      This menu is provided for the people who were using another cruncher or
  230. an older version of PowerPacker.  Just select 'Recrunch File' or 'Decrunch
  231. Only' and load the file.  PowerPacker will start the correct decrunch
  232. algorithm.  If you selected 'Recrunch' PowerPacker will start to crunch the
  233. decrunched file.  If PowerPacker doesn't recognize the cruncher it will say
  234. so, no harm is done.  If you select 'Recrunch Always' PowerPacker will always
  235. recrunch, even if the file was crunched with this version of PowerPacker.
  236. Useful for recrunching files using a higher efficiency.  (e.g. recrunch a
  237. 'Fast' crunched file with 'Best')
  238.  
  239.      Crunchers currently supported are:  'ANC Cruncher', 'TNM Cruncher 1.1',
  240. 'Relokit 1.0', 'HQC Cruncher 2.0', 'MasterCruncher 3.0', 'DragPack 1.0' and
  241. older PowerPacker files.  If you'd like to see other crunchers supported,
  242. send me the cruncher and some programs crunched with it.  (Together with a
  243. contribution I hope).  If it is possible to develop a decrunch algorithm I
  244. will include it in the next version of PowerPacker.
  245.  
  246. 2.2 Why ?
  247.  
  248.      PowerPacker always crunches better than the 'ANC Cruncher', 'TNM
  249. Cruncher' and 'HQC Cruncher'.  It crunches better than 'Relokit' most of the
  250. time, but even if it doesn't, I advise you to recrunch because 'Relokit' has
  251. some serious disadvantages (e.g. while the decrunched file is running, the
  252. crunched version still eats memory).  In contrast PowerPacker only eats about
  253. 530 bytes while your file is running, and (of course) frees it afterwards.
  254.  
  255. NOTE: - If you want to recrunch a PowerPacker 1.1 or 2.0 crunched file,
  256.         PowerPacker just replaces the file header with the improved and
  257.         debugged 2.1+ header. (Unless you've selected 'Recrunch Always')
  258.       - The recrunch menu only supports command files !  You can't recrunch
  259.         data files from e.g. PowerPacker 1.1, sorry.
  260.       - 'Decrunch Only' is not 100% guaranteed for 'Relokit 1.0' files,
  261.         'Recrunch' however is 100% ok ! (It's a strange world ! :-)
  262.       - Several people sent me 'dirty' crunchers, these are crunchers that
  263.         use absolute addresses (an absolute TABOO !!!).  It is impossible
  264.         to develop a decrunch algorithm for these.  (In fact, nothing should
  265.         have been crunched with these crunchers in the first place !)
  266.  
  267.  
  268. 3. The Hunklab
  269. --------------
  270.  
  271. 3.1 Preferences
  272.  
  273.      This menu is not really part of the PowerPacker crunch/decrunch routines
  274. but it wasn't worth writing a separate program for and a HunkLab is after all
  275. a very interesting utility.  You can e.g. use it to remove symbol and debug
  276. hunks from files that wouldn't crunch otherwise.
  277.  
  278.      You can force a program's code, data or BSS (uninitialised data) into
  279. chip ram or you can remove symbol tables and debug information just by
  280. toggling the marker on/off.  So in future, when you want your programs to be
  281. able to run on a one megabyte system, a simple click on the mousebutton will
  282. do.
  283.  
  284. 3.2 Process file
  285.  
  286.      'Process file' reads the file from disk and changes it according to your
  287. preferences.  To save the processed file, use 'Save' from the Project menu.
  288.      'Process & Crunch' will process the file and crunch the file afterwards
  289. (if possible).  To save use 'Save' in the Project menu.
  290.  
  291. NOTE: - Debug and symbol hunks are only used in debuggers, so you can safely
  292.         remove them from a program. (Unless you want to debug the program.)
  293.  
  294.  
  295. 4. The Script Menu
  296. ------------------
  297.  
  298.      The script is something that will save you a lot of time, it allows you
  299. to record 80 different commands to be executed after each other.  It is ideal
  300. for crunching a lot of files overnight.  Menu options are:
  301.  
  302.      'Clear Script' and 'List Script':
  303.           will do just that.
  304.      'Script Log File':
  305.           is used to specify a file to redirect output to.  If you cancel
  306.           the requester no log file is used.
  307.      'Destination Dir':
  308.           is used to specify the directory to save to.  It is ghosted in
  309.           normal use.
  310.      'Start Recording':
  311.           is used to start the recording of the script. If the script was
  312.           empty you will be asked for the destination directory.
  313.               After selecting the destination you can start entering the
  314.           script commands.  Everything that is ghosted is not available as a
  315.           command.  Just enter everything as if you were actually using
  316.           PowerPacker.  When you e.g. choose 'Load' PowerPacker will ask a
  317.           list of files to be (de)crunched. Press 'CANCEL' to exit the
  318.           entry.
  319.           NOTE: - You can still change the source and destination dir while
  320.                   recording.
  321.           Every command you enter will be displayed in the supervisor window.
  322.      'Stop Recording':
  323.           is used to exit the recording mode.
  324.      'Delete Last':
  325.           will delete the last command after a confirmation.
  326.      'Execute Script':
  327.           will start the playback of the script commands.  If you press the
  328.           menu button a requester will appear to ask you if you want to abort
  329.           the script execution.
  330.               After executing the script a request to clear the script will
  331.           appear.
  332.  
  333. NOTE: - It is advisable to let the filerequester buffer fill before you
  334.         start selecting files.  It is also better not to change the source
  335.         directory too often.
  336.       - The screen turns grey to indicate a script is executing.
  337.       - While executing a script, PowerPacker will always act destructive !
  338.         Files will allways be overwritten and deleted !!!
  339.  
  340.  
  341. 5. The Supervisor Window
  342. ------------------------
  343.  
  344.      This window displays all kind of useful information like the file
  345. status, crunch messages, and error messages.  You can follow all steps, from
  346. the original file that is loaded into memory, to the final crunched version
  347. on disk.  When an executable file is loaded, its hunk information is
  348. displayed.  This information is rather technical, but it can be useful for
  349. programmers.  If you're not interested, just ignore it.
  350.  
  351.      I think it might be useful to give a list of possible error messages:
  352.  
  353. (De)crunch :  Buffer overflow !
  354.                 (Crunched file is getting longer than original file)
  355.               Crunch aborted !
  356.                 (Crunching stopped by user or by buffer overflow)
  357.               No memory for decrunch buffer !
  358.               Out of memory !
  359.                 (Buy some more, try selling your WorkBench :-)
  360.               Sorry, can't crunch !
  361.                 (This is a polite program)
  362.               Can't find hunk_header.
  363.               Hunk not allowed in load file!
  364.               Unknown Hunk !
  365.                 (Not a command file)
  366.               Hunk not supported (yet ?) !
  367.                 (If it's a symbol or debug hunk, try removing it in HunkLab)
  368.               Nothing to save !
  369.                 (Buffer is empty)
  370.               Save Aborted !
  371.               Error reading file !
  372.               Can't open file !
  373.               Error writing data header !
  374.               Error writing buffer !
  375.               File not found !
  376.               Couldn't delete file !
  377.               Can't open file !
  378.                 (Disk errors)
  379.  
  380. Recrunch :    No need to recrunch 'PowerPacker 1.1' command file,
  381.               Replacing 1.1 decrunch header with 2.3 header...
  382.                 (2.1+ header is shorter and bugfree, 1.1 isn't !!)
  383.               No need to recrunch 'PowerPacker 2.0' command file,
  384.               Replacing 2.0 decrunch header with 2.3 header...
  385.                 (There was still a small bug in 2.0 header, so replace it.)
  386.               Not crunched with one of the supported crunchers !!
  387.                 (Or file isn't crunched at all !)
  388.               Sorry, can't recrunch !
  389.                 (Please don't sue me :-)
  390.  
  391. Process :     Sorry, can't process file !
  392.                 (File is probably not a command file)
  393.               Can't crunch file !
  394.                 (File contains unsupported hunks)
  395.  
  396. Script :      Script buffer full !! Please stop recording.
  397.                 (Script is limited to 80 commands, select 'Stop Recording')
  398.  
  399.  
  400. 6. A Sample Session
  401. -------------------
  402.  
  403.      Now that I have explained PowerPacker's capabilities, it's time for
  404. a little demonstation.  Let's say we want to crunch the 'CLI' command in the
  405. System directory on your Workbench 1.2 disk.
  406.  
  407.      Select 'Pointer' in the Prefs/Decrunch Color menu (When I wrote this
  408. text, it was very late and I couldn't stand the other decrunch colors
  409. anymore !)
  410.  
  411.      Set 'Prefs' to 'Command file'.  Now select 'Load' in the Project menu
  412. (the file requester will appear), insert your WorkBench 1.2 disk and choose
  413. the 'CLI' command in the system directory.  Now you'll see a lot of hunk
  414. (or junk ?? :-) information about the CLI command:
  415.  
  416.                                                                              
  417.      Scanning file 'df0:System/CLI'...                                       
  418.      Loading command file...                                                 
  419.                                                                              
  420.      Hunk_header (0x03F3)                                                    
  421.      9 hunks (0 to 8).                                                    
  422.      Hunk  0 : Hunk_code (0x03E9)     (524 bytes)                            
  423.      Hunk_reloc32 (0x03EC)                                         
  424.      Hunk  1 : Hunk_data (0x03EA)     (428 bytes, 0 BSS)                     
  425.      Hunk  2 : Hunk_code (0x03E9)     (472 bytes)                            
  426.                Hunk_reloc32 (0x03EC) 
  427.      Hunk  3 : Hunk_data (0x03EA)     (52 bytes, 0 BSS)                      
  428.      Hunk  4 : Hunk_code (0x03E9)     (16 bytes)                             
  429.      Hunk  5 : Hunk_code (0x03E9)     (0 bytes)                              
  430.      Hunk  6 : Hunk_code (0x03E9)     (196 bytes)                            
  431.                Hunk_reloc32 (0x03EC)                                         
  432.      Hunk  7 : Hunk_code (0x03E9)     (68 bytes)                             
  433.                Hunk_reloc32 (0x03EC)                                         
  434.      Hunk  8 : Hunk_data (0x03EA)     (0 bytes, 0 BSS)                       
  435.  
  436.      Crunching command file...                                               
  437.      Press left and right button to abort.                                   
  438.      Crunching, please wait.                                                 
  439.  
  440.      The cruncher displays the percentage of the file already crunched and
  441. the gain so far. After some time your screen will look like this:
  442.  
  443.                                                                              
  444.      100% crunched.                                                          
  445.      Done.                                                                   
  446.      Original length : 2356 bytes.                                           
  447.      Crunched length : 1204 (1776) bytes.                                    
  448.      Gained 49% (1152 bytes) !                                               
  449.  
  450.      The only thing you have to do now is save this back to disk as an
  451. executable file.  Now enjoy the crunched CLI command.
  452.  
  453.  
  454. 7. PowerPacker 2.3a & the CLI
  455. -----------------------------
  456.  
  457.      For your convenience, I have also written two CLI commands, one to
  458. crunch and one to decrunch data files.
  459.      From version 2.3 onwards the CLI commands use the magnificent ARP
  460. library !!!  This means they have been greatly enhanced:  wildcards are fully
  461. supported, options can be entered in any order, directories will be created
  462. when needed, etc...  Make sure the arp.library is in your LIBS:  directory
  463. when you run these commands.
  464.      A usage line is given by typing 'Crunch' or 'Decrunch' without
  465. arguments.  You'll get something like this:
  466. _____________________________________________________________________________
  467.  
  468. 1> Crunch
  469. POWER-PACKER 2.3a Data Cruncher.
  470.   Written by Nico Francois (POWER PEAK)
  471. Usage : Crunch <source> <destination> [EFFICIENCY 1-5] [COLOR 0-4] [CRYPT]
  472.                                       [NOSUFF] [NOLED] [FORBID] [NOPER]
  473. With:
  474.   EFFICIENCY: 1 = Fast, 2 = Mediocre, 3 = Good (def), 4 = Very Good, 5 = Best
  475.   COLOR     : 0/1 = Color 0/1, 2 = Pointer (def), 3 = Scroll, 4 = None
  476.   CRYPT     : Encrypt file.
  477.   NOSUFFIX  : Don't attach '.pp' suffix to filename.
  478.   NOPER     : Don't print percentage.
  479.   NOLED     : Disable led crunch.
  480. Hit ^C to abort, ^D to abort crunching only.
  481.  
  482. 1> Decrunch
  483. POWER-PACKER 2.3a Data Decruncher.
  484.   Written by Nico Francois (POWER PEAK)
  485. Usage : Decrunch <source> <destination> [COLOR 0-4] [OPT B|F] [SKIP] [QUIET]
  486. With:
  487.    COLOR: 0/1 = Color 0/1, 2 = Pointer (def), 3 = Scroll, 4 = None
  488.    SKIP : Skip uncrunched files.
  489.    QUIET: Be quiet.
  490. If <destination> is '*' or is omited, files will be typed to Output().
  491. Options effective when typing:
  492.    OPT B will print a banner before and
  493.    OPT F will print a formfeed after each file.
  494. Hit ^C to abort, ^D to abort typing only.
  495.  
  496. 1>
  497. _____________________________________________________________________________
  498.  
  499.      These commands are useful to be included in your startup-sequence or to
  500. read crunched text files quickly.
  501.  
  502.   Some examples:
  503.  
  504.      Crunch df0:source/*.c TO ram:source COL 4 NOLED
  505.  
  506.      This will result in a crunching of every C program in the df0:source
  507. directory.  If the ram:source directory exists the files will be saved there,
  508. if it doesn't it will be created if there is more than one C program in
  509. df0:source.  The '.pp' suffix will be attached to the filenames.  The led
  510. will not flicker, no crunch color is used.
  511.  
  512.      Decrunch >PRT: QUIET dh0:progs/*.asm.pp OPT BF COL 3
  513.  
  514.      Every crunched assembler program will be decrunched and printed, before
  515. each file a banner will be printed, each file will start on a new page.  If
  516. the file is encrypted you will be prompted for a password.  It is very
  517. important that you use the QUIET option here, if you don't the copyright and
  518. information lines will also be printed.  The mouse pointer will flash while
  519. decrunching.
  520.  
  521. NOTE: - These commands only (de)crunch DATA files !!!!  (So to (de)crunch
  522.         executable files, you'll still have to use PowerPacker 2.3a).
  523.  
  524.  
  525. 8. PowerPacker 2.3a & other programs
  526. ------------------------------------
  527.  
  528. 8.1 Introduction
  529.  
  530.      This one is for the programmers among you !
  531.      From release 2.3 onwards the decrunch source is included.  I decided to
  532. do this so other programs could load data files crunched with PowerPacker.
  533. As an example I could refer to one of my other utilities : PPMore, this is a
  534. text viewing utility (like more, hence the name) that can also display ASCII
  535. files crunched with PowerPacker.
  536.      Source is presented as a support function 'PP_LoadData', this function
  537. will load a data file and will decrunch it if necessary.  When the file isn't
  538. crunched it'll just be loaded.  Encrypted files are also supported.
  539.      The source was written for Aztec C 3.6a.  If you want to compile it with
  540. Lattice you will have to seperate C and assembler, compile/assemble them
  541. separatly and link them together.  You can use this code for non-commercial
  542. programs as long as you leave my copyright notice intact.
  543.  
  544. 8.2 The function
  545. _____________________________________________________________________________
  546.  
  547.   error = PP_LoadData (file, color, typeofmem, buffptr, lengthptr, password);
  548.  
  549.   with:
  550.      char *file;         filename of file to be loaded
  551.      UBYTE color;        decrunch color (see ppdata.h)
  552.      ULONG typeofmem;    type of memory to be allocated
  553.      UBYTE **buffptr;    address of buffer pointer variable
  554.      ULONG *lengthptr;   address of length variable
  555.      char *password;     pointer to password string or NULL
  556.  
  557.   Note:
  558.      - error and color codes are defined in <ppdata.h>.
  559.      - memory must be freed by caller after usage : FreeMem (buff, length);
  560. _____________________________________________________________________________
  561.  
  562.      You have the following decrunch colors available:
  563.  
  564.           DECR_COL0      Decrunch in color 0
  565.           DECR_COL1         ''    '' color 1
  566.           DECR_POINTER      ''    '' the mouse pointer
  567.           DECR_SCROLL       ''    '' the scroll register
  568.           DECR_NONE      No decrunch color is used
  569.  
  570.      The following errors can occure:
  571.  
  572.           PP_LOADOK      No error, file loaded succesfully.
  573.           PP_LOCKERR     Couldn't lock file, file probably doesn't exist.
  574.           PP_OPENERR     Couldn't open file.
  575.           PP_READERR     Read error.
  576.           PP_NOMEMORY    No memory to allocate buffer for data file.
  577.           PP_CRYPTED     File is crypted and no password was provided.
  578.           PP_PASSERR     File is crypted and wrong password provided.
  579.  
  580. 8.3 Loading encrypted files
  581.  
  582.      To load encrypted files a password has to be provided to the function.
  583. First of all try to load the file with a NULL pointer for 'password', when
  584. you get the PP_CRYPTED error you know that the file is encrypted.  Then
  585. prompt the user for a password and call the function again with the same
  586. parameters, but now 'password' points to the password string.  If PP_LoadData
  587. returns PP_LOADOK the file was decrypted, if it returns PP_PASSERR the
  588. password was incorrect.  If it returns anything else some sort of error
  589. occured (see <ppdata.h> for the error codes).
  590.  
  591. 8.4 Compiling and linking
  592.  
  593.      - If you use Aztec C you have one module to compile : ppdata.c
  594.  
  595.      cc [options] ppdata.c
  596.  
  597.      Use the same options you use in the other modules of your program.
  598. Compile the other modules of your program and link everything together:
  599.  
  600.      ln +q main.o ... ppdata.o -lc -o myprog
  601.  
  602.      - If you use Lattice C you will have to seperate the C source from the
  603. assembler source and compile/assemble them seperatly.  You will then get two
  604. object files.  When you then link everything together be sure to link with
  605. both these object files.  (I haven't tried it, but it should work)
  606.  
  607. 8.5 An example
  608.  
  609.      This small (incomplete) program shows you how to use the support
  610. function in your programs.
  611.  
  612. /*********
  613. * test.c *
  614. *********/
  615.  
  616. #include <exec/types.h>
  617. ...
  618. #include <ppdata.h>
  619.  
  620. UBYTE *buffer = NULL;
  621. ULONG bufferlength;
  622. UBYTE password[17];
  623.  
  624. main()
  625. {
  626.      int error;
  627.  
  628.      error = PP_LoadData ("df0:doc/Packer.doc.pp", DECR_POINTER, MEMF_PUBLIC,
  629.           &buffer, &bufferlength, NULL);     /* Don't forget the '&' !!!!! */
  630.      if (error != PP_LOADOK) switch (error) {
  631.           case PP_LOCKERR:
  632.                puts ("file not found !!!");
  633.                FreeStuffAndExit();
  634.           case PP_LOADERR:
  635.                puts ("loading error !!!");
  636.                FreeStuffAndExit();
  637.           case PP_NOMEMORY:
  638.                puts ("out of memory !!!");
  639.                FreeStuffAndExit();
  640.           ...
  641.           case PP_CRYPTED:
  642.                /* prompt the user for a password (max 16 chars) */
  643.                ...
  644.                error = PP_LoadData ("df0:docs/Packer.doc.pp", DECR_POINTER,
  645.                     MEMF_PUBLIC, &buffer, &bufferlength, password);
  646.                if (error == PP_PASSERR) {
  647.                     puts ("incorrect password !!!");
  648.                     FreeStuffAndExit();
  649.                     }
  650.                else if (error != PP_LOADOK) {
  651.                     puts ("correct password, but couldn't load !!!");
  652.                     FreeStuffAndExit();
  653.                     }
  654.                break;
  655.           }
  656.      /* now do something with the data file loaded at addr 'buffer' and with
  657.         length 'bufferlength' */
  658.      ...
  659.      /* DO NOT FORGET TO FREE THE MEMORY !! */
  660.      FreeMem (buffer, bufferlength);
  661. }
  662.  
  663. FreeStuffAndExit()
  664. {
  665.      /* free all your resources */
  666.      ...
  667.      exit (0);
  668. }
  669.                                              Enjoy this program !!!
  670.  
  671.  
  672.                               PROGRAM HISTORY:
  673.  
  674. *****************************************************************************
  675. VERSION 1.0a
  676.  
  677.      First release.
  678.  
  679. *****************************************************************************
  680. VERSION 1.1a
  681.  
  682.      Fixed bugs.
  683.      Improved crunch algorithm by about 5%.
  684.      'Delete' and 'Multitask' added.
  685.      Better menu structure.
  686.      Improved the file requester.
  687.      Written CLI commands.
  688.  
  689. *****************************************************************************
  690. VERSION 2.0a
  691.  
  692.      Fixed some more bugs.
  693.      Added buffer and automatic device-list to the file requester.
  694.      Added 'LED Crunch', useful for turning the monitor off while crunching,
  695.      and 'Paging'.
  696.      New header, bug fixed. (1.1 didn't free mem when started from WorkBench)
  697.      Added the hunklab.
  698.      Improved CLI commands.
  699.  
  700. *****************************************************************************
  701. VERSION 2.1a
  702.  
  703.      Fixed last bug in header (2.0 crashed when you were out of memory, oops)
  704.      Added script feature, now possible to crunch files overnight.
  705.      Improved requesters.
  706.      Automatic crunch/decrunch.
  707.      Improved menu structure considerably.
  708.      Intelligent recrunch implemented.
  709.      Automatic crunch/decrunch.
  710.      Added 'Color Crunch' option.
  711.      New efficiency 'Best' added.
  712.  
  713. *****************************************************************************
  714. VERSION 2.1b
  715.  
  716.      Bug fixed in script abort.
  717.      Added ability to open a log file during script execution.
  718.      Now possible to recrunch PowerPacker files with a higher efficiency.
  719.      Recrunch detects unsupported crunchers a lot faster.
  720.      PowerPacker now automatically opens a PAL/NTSC screen.
  721.  
  722. *****************************************************************************
  723. VERSION 2.2a
  724.  
  725.      All known bugs (or better, undocumented features) fixed.
  726.      'Sleep' mode implemented, useful for multitasking freaks.
  727.      While crunching the gain percentage so far is displayed.
  728.      Recrunch now supports 'HQC Cruncher 2.0', 'MasterCruncher 3.0'
  729.        and 'Dragpack 1.0'.
  730.      New graphics in title.
  731.  
  732. *****************************************************************************
  733. VERSION 2.3a
  734.  
  735.      PowerPacker detaches itself from the CLI, so the CLI window can be
  736.        closed or used for other things.
  737.      CLI commands are greatly enhanced, they now use ARP.
  738.      New switch : 'Overwrite' to surpress 'OK to overwrite ?' request.
  739.      File requester now able to sort files, 'Sort files' switch.
  740.      By popular demand: encryption of data files is now possible using the
  741.        new 'Encrypt Data' switch. Encryption should be IMPOSSIBLE to crack !!
  742.      Also by popular demand: Now possible to save preferences to boot disk.
  743.      More memory efficient decrunch and recrunch of PowerPacker files.
  744.      Decrunch source included, so other programs could be written that
  745.        would load data files crunched with PowerPacker.
  746.      'Data Suffix' switch to improve adding/removing of '.pp' suffix.
  747.      Decrunch color default 'Pointer'.
  748.      Improved scanning of files when loading or recrunching.
  749.      Fixed small bug (version 2.2a lost 256 bytes every time it was run).
  750.      More info in about window.
  751.  
  752. *****************************************************************************
  753.  
  754. P.S. This text file crunches to 43% of it's original length. (Gains 57% !)
  755.  
  756. PowerPacker 2.3a written by Nico Francois (Yes, Nico is my first name :-)
  757. Special thanks go to - Luc Pauwels for the icons and writing the 2.0a manual,
  758.                      - Jorrit Tybergein for the extensive debugging.
  759.                      - everybody who mailed me suggestions or remarks.
  760.  
  761. (c) 1989 Nico Francois / Power Peak
  762.  
  763.                                    //
  764.                        Thanks to \X/ Amiga for being the best computer ever !
  765.  
  766.